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PORTABLE DUAs 


Status of this Memo 


This memo provides information for the Internet community. It does 
not specify an Internet standard. Distribution of this memo is 
unlimited. 

INTRODUCTION 


This document comes in two parts. The first part is for regular 
people who wish to set up their own DUAS (Directory User Interfaces) 
to access the Directory. It includes some brief notes on the 
operation of the DUAs and instructions for their creation and 
installation. The instructions are given in an easy-to-follow, step- 
by-step format. It is fully expected that the user will be able to 
perform the necessary operations as he reads through the instructions 
for the first time and have a working DUA when he finishes. The 
second part is for ISODE-maintainers wishing to provide portable DUAs 
to users. This part gives instructions in a similar but longer, 
step-by-step format. It is fully expected that the maintainer will be 
able to perform the necessary operations as he reads through the 
instructions for the first time and have a working DUA 
package/supporting service when he finishes. 


The document currently has four sub-parts for each larger part. The 
sub-parts detail the following DUAs: WHOIS, "de," dixie’s "ud" and 
ISODE’s "doog." It is intended that additional sub-parts will be 
added to the document as new, portable DUA packages are designed. 
Where pertinent, the document assumes ISODE 8.0 is being used. 

1. Instructions for DUA-Users 

WHOIS 

A WHOIS interface to X.500 may be available on any ISODE-resident 
machine which also runs a DSA (Directory System Agent.) Check with 
your local, ISODE-maintainer. If the service is available, users can 


access the Directory with the following command: 


whois -h <hostname> <name in UFN format> 
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<hostname> indicates the name of the host machine offering the WHOIS 
interface, surrounded by quotes. <name in UFN format> refers toa 
special, user-friendly syntax developed by Steve Hardcastle-Kille. 
UFN format is a comma-separated list of DN component values. 
(Attribute types are omitted.) The criteria for identifying DN 
components in UFN is often less stringent than normal. For example: 


@c=US@st=California@o=Information Sciences 
Institute@ou=HPCC@cn=Tom Tignor 


could be uniquely specified in UFN syntax as 
tignor,isi,ca,us 
So to find this entry through WHOIS, one would type: 
whois -h "gum.isi.edu" tignor,isi,ca,us 
See Steve Hardcastle-Kille’s Work in Progress, "User Friendly Naming" 
for details. 
De 
Use of the "de" DUA is fully explained by the program’s help section. 
New users should type "?" at the first prompt after installing and 


running the de executable. 


The de executable can be created and installed by the following 
simple steps: 


If you do not have a file called ".unknown_tailor" in your home 
directory, create it now. This file should contain the following 
single line: 

etcpath: <fullpathname>/isode/etc/ 


where <fullpathname> is the full path name of your SHOME 
directory. 


If you do not have a directory S$HOME/isode/bin, where "$HOME" is 
your home directory, create it now. 


ftp the compressed tar file "de-portable.tar.Z" from your local, 


ISODE-resident machine and put it in your isode directory. If 
you cannot find this file locally, it is available by anonymous 
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ftp from "gum.isi.edu" in the "x500" directory. 

cd $HOME/isode 

uncompress < de-portable.tar.Z | tar xf - 

If your name is listed in the Directory, edit the de/detailor 
file and add a line reading: 


username: <yourDN> 


where <yourDN> indicates your Distinguished Name in the 
Directory. 


cp de/detailor de/etc/detailor 

Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to 
refer to your isode/bin, isode/etc and isode/etc directories, 
respectively. (The isode/etc directory was created by the 
previous command.) 

ranlib libdsap.a 

ranlib libisode.a 

cd de 

./make all 


./make inst-all 


There is one error you may encounter during this procedure, following 
the "./make all" command: 


"Redeclaration of sprintf." in general.h 


If this error occurs, the following sub-procedure will fix the 
problem: 


Invoke your editor for the file ../h/general.h 

Search for the string "sprintf". 

Cut the line with the "#endif" string which follows the line 
reading: 


char *sprintf (); 


Paste the line under the line which reads "#endif". This second 
#endif line is exactly three lines below the current line. 
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Save the file and quit the editor. 


Type "./make all" again. It should now compile smoothly. Finish up by 
typing "./make inst-all". 


Dixie/Ud 


The "ud" DUA is designed for users doing most of their X.500 queries 
in one branch of the DIT (Directory Information Tree.) The DUA 
operates from a predefined "base," a position in the DIT one or more 
branches above the entries to be queried. The base is usually an 
organization name, such as: 


@c=US@st=California@o=Information Sciences Institute 
Ud starts with a preset base. (See below.) But this base can be 
changed with the "cb" command. "cb" takes the full DN of the new base 


as an argument. For example: 


cb @c=GB@o=University College London 


With a preset base, searching is easy. The user finds entries below 
the base with the "find" command. "find" takes the last component of 
the DN of the entry as its sole argument. The criteria for the 
argument is very loose. The partial matching performed by ud should 
return the desired data or a clarification request if the name is at 
all close to the real thing. 


For example, with a base "@c=US@st=California@o=Information Sciences 
Institute", the RDN 


ou=HPCC@cn=Tom Tignor 
could be found by entering 
find tignor 
at the ud prompt. 
Other commands in ud are briefly described by the program’s help 


section. Interested users should type "?" at the first prompt, after 
installing and running the executable. 


"Ud" comes with the "dixie" package, a mini-environment designed 
specifically to support lightweight Directory access. Using ud 
requires that a dixie server is running along with a DSA on your 
local, ISODE-resident machine. Before retrieving the dixie package, 
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check with your local DSA manager to see that the dixie server is up 
and running. 


Once 


you’re sure that everything is set up at the DSA-manager’s end, 


the ud executable can be created and installed by the following 


simpl 


e steps: 


If you do not have a directory $HOME/isode/bin, where "$HOME" is 
your home directory, create it now. 


ftp (anonymously) the compressed tar file "dixie-<version 
#>.tar.Z", where <version #> is the number of the latest 
release, from "terminator.cc.umich.edu" and put it in your isode 
directory. The file is available in the "x500" directory on 
terminator. 


cd SHOME/isode 


uncompress < dixie-<version #>.tar.Z | tar xf - 
This creates the dixie environment. As a user interested in ud only, 
there are a number of things in the package that will be taking up 
space to no purpose. The following sequence of commands will get rid 
of them. 

cd dixie-<version #> 

rm -r dos 

rm -r macintosh 

rm -r server 

rm -r vms 

cd 
That done, we continue to bring ud to life. 


Tignor 


cd dixie-<version #> 


Edit the file "ud/ud.h". There are two constants for which you 
will need to supply new values: DEFAULT_BASE and DEFAULT_SERVER. 
DEFAULT_BASE identifies ud’s "base" upon startup, as described 
above. It takes a quoted DN as a value, e.g., 
"@c=US@st=California@o=Information Sciences Institute". 
DEFAULT_SERVER identifies the machine which hosts the dixie 
server, i.e. your local, ISODE-resident machine. This constant 
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takes a quoted string as a value, e.g., "gum.isi.edu". 

Edit the file "Makefile". Set the value of the BINDIR variable 
to "<mypath>/isode/bin", where <mypath> is the full pathname of 
the user’s home directory. 

make depend-ud 


make ud-only 


make inst-ud 


Doog 


The "doog" DUA retrieves information on entries supplied by the user 
in UFN format. UFN format refers to a special, user-friendly syntax 
developed by Steve Hardcastle-Kille. UFN format is a comma-separated 
list of DN component values. (Attribute types are omitted.) The 
criteria for identifying DN components in UFN is often less stringent 
than normal. For example: 


@c=US@st=California@o=Information Sciences 
Institute@ou=HPCC@cn=Tom Tignor 


could be specified in UFN syntax (and doog) as 
tignor,isi,ca,us 


See Steve Hardcastle-Kille’s Work in Progress, "User Friendly Naming" 
for details. 


Other commands in doog are briefly described by the program’s help 
section. Interested users should type "?" at the first prompt, after 
installing and running the executable. 


The doog executable can be created and installed by the following 
simple steps: 
If you do not have a file called ".unknown_tailor" in your home 
directory, create it now. This file should contain the following 
single line: 


etcpath: <fullpathname>/isode/etc/ 


where <fullpathname> is the full path name of your SHOME 
directory. 


If you do not have a directory S$HOME/isode/bin, where "$HOME" is 
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your home directory, create it now. 
ftp the compressed tar file "doog-portable.tar.Z" from your 
local, ISODE-resident machine and put it in your isode 
directory. If you cannot find this file locally, it is available 
by anonymous ftp from "gum.isi.edu" in the "x500" directory. 
cd $HOME/isode 
uncompress < doog-isode-8.0.tar.Z | tar xf - 
Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to 
refer to your isode/bin, isode/etc and isode/etc directories, 
respectively. (The isode/etc directory was created by the 
previous command.) 
ranlib libdsap.a 
ranlib libisode.a 
cd doog 
./make all 
./make inst-all 
2. Instructions for ISODE-Maintainers 
WHOIS 
"WHOIS" is a simple program already available at most UNIX 
workstations and hosts. It is normally used to access the database of 
users at NIC.DDN.MIL. The instructions below explain how to use WHOIS 
to access data in the White Pages Pilot X.500 database. These 
instructions are taken nearly word for word from the "PSI White Pages 
Pilot Project Administrator’s Guide," section 2.8.3. 
Choose a machine in your local environment which is running the pilot 
project software. This machine will offer the white pages service via 


a network port offering an emulation of the WHOIS service. 


On this machine, modify the /etc/services file so that it contains an 
entry like this: 


whitepages 17005/tcp 


Next, edit the file /etc/servers so that it has an entry like this: 
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whitepages tcp $(SBINDIR)in.whitepages 


Because most user interfaces to WHOIS, e.g., whois(lc), do not allow 
the user to specify a special port, you should probably also add this 
line as well: 


whois tcp$(SBINDIR) in.whitepages 
If you already have a line for whois in the servers file, then you 
are already running a WHOIS service, and you should NOT add a second 
whois line. This machine is not a good choice for running the white 


pages via WHOIS emulation. 


Note that on newer systems derived from Berkeley UNIX, /etc/servers 
is called /etc/inetd.conf. 


The whitepages Command 
On those systems which are to access the white pages via the network 
and not locally (i.e., those systems which are not running the pilot 
project software), you should determine how the user invokes the 
WHOIS service via the network. For UNIX systems, you should provide a 
shell script like this: 

run this script through /bin/sh 

exec /usr/ucb/whois -h wp.psi.net "$*" 
where the name of a host running the pilot project software is 
substituted for whitepages, e.g., wp.psi.net. This host must have the 
files /etc/services and /etc/servers edited as described above. 
De 
The compressed tar file for "de" can be created by the following 
sequence of commands. (Note: In the instructions which follow, 
<toplevel> indicates the top level of the ISODE distribution.) 


cd <toplevel>/others/quipu/uips 


Edit the de/detailor file to set the following options: 


dsa_address: (the address of your DSA) 
default_country: (your country) 
default_org: (your organization) 


cp de/make temp1 
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Edit the de/make file so that the last line reads as follows: 


exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"S@"} 
tar -cf de-portable.tar de/* 
mv temp1 de/make 
mv de-portable.tar <aboveETCDIR> 
(Here, <aboveETCDIR> is the directory immediately above 
ETCDIR.) 


cd <aboveETCDIR> 


tar -rf de-portable.tar etc/dsaptailor etc/isomacros 
etc/oidtable.at etc/oidtable.oc etc/oidtable.gen 


mv de-portable.tar <toplevel> 
cd <toplevel> 
cp config/CONFIG.make 


tar -rf de-portable.tar h/* h/quipu/* util/* CONFIG.make 
libdsap.a libisode.a 


rm CONFIG.make 
compress de-portable.tar 


The compressed tar file for de will appear in the top level directory 
of the ISODE distribution as "de-portable.tar.2Z". 


Dixie/Ud 


The latest version of the dixie distribution is available by 
anonymous ftp at "terminator.cc.umich.edu" in the "x500" directory. 
The file is named "dixie-<version #>.tar.Z", where <version #> is the 
number of the latest release. 


In order for anyone to use dixie clients, there must be a running 
dixie server which they can connect to. To set up the dixie server, 
the DSA manager should take the dixie package and explode/uncompress 
it in the top level directory of the ISODE distribution. This is done 
with the following command: 


uncompress < dixie-<version #>.tar.Z | tar xf - 


Tignor [Page 9] 


RFC 1373 DSA Support for Portable DUAs October 1992 


where <version #> is the version number of your dixie package. This 
will create a "dixie-<version #>" directory. The dixie server, dixie 
library and any DUAs included with the package will be in this 
directory branch. Software to support dixie on machines other than 
UNIX is included as well. This software is stored in the directories 
"dos", "macintosh" and "vms". UNIX users should feel free to delete 
these directories and all their contents. Commands of the form: 


rm -r <dirname> 
where <dirname> is the directory name, should accomplish this task. 
In the top level of the dixie distribution is a file called 


"Makefile". The file holds several variables which should be 
configured to match those of your ISODE environment. 


BINDIR ISODEINCLUDEDIR 
ETCDIR LIBDIR 
INCLUDEDIR ISODELIBS 
INSTLIBDIR 


In the "server" directory below the top level of the dixie 
distribution is another "Makefile" file. Configure the ISODELIBS 
variable in this file, as well. 


After setting these variables, cd to the top level of the dixie 
distribution and type the following commands: 


make depend-server 


make server-only 
make inst-server 


This will create and install the dixie server in your ETCDIR. cd to 
the ETCDIR and type "dixie" to start the server. 

Doog 

The compressed tar file for "doog" can be created by the following 
sequence of commands. (Note: In the instructions which follow, 
<toplevel> indicates the top level of the ISODE distribution.) 


cd <toplevel>/others/quipu/uips 


cp doog/make temp1 
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Edit the doog/make file so that the last line reads as follows: 
exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"S@"} 
cp doog/query/make temp2 


Edit the doog/query/make file so that the last line reads as 
follows: 


exec $M TOPDIR=../../ -f ../../CONFIG.make -f Makefile 
${1+"se"} 


tar -cf doog-portable.tar doog/* 
mv templ doog/make 

mv temp2 doog/query/make 

mv doog-portable.tar ../../.. 

rato RERE rary ener 

cp config/CONFIG.make 


tar -rf doog-portable.tar h/* h/quipu/* util/* CONFIG.make 
libdsap.a libisode.a 


rm CONFIG.make 

mv doog-portable.tar <aboveETCDIR> 
(Here, <aboveETCDIR> is the directory immediately above 
ETCDIR.) 


cd <aboveETCDIR> 


tar -rf doog-portable.tar etc/dsaptailor etc/isomacros 
etc/oidtable.at etc/oidtable.gen etc/oidtable.oc 


compress doog-portable.tar 


The compressed tar file for doog will appear in the directory 
immediately above ETCDIR as "doog-portable.tar.Z". 


Security Considerations 


Security issues are not discussed in this memo. 
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